home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / PROGRAMM / DB_CLIPP / 0240.ZIP / DG_DOC.TXT < prev    next >
Text File  |  1986-08-19  |  22KB  |  517 lines

  1.                      dGENERATE Documentation
  2.  
  3.                    (Version 1.0: August, 1985)
  4.                     (Revised August 15, 1985)
  5.  
  6.    Copyright 1985, Tom Rettig Associates, All Rights Reserved
  7.   9300 Wilshire Boulevard, Suite 470, Beverly Hills, CA  90212
  8.     (213)272-3784 -- Source: BCR480 -- CompuServe: 75066,352
  9.  
  10.  
  11. dGENERATE is a dBASE III screen and code generator written 
  12. entirely in dBASE III.  The generated code is intended to assist 
  13. rather than replace the application programmer.
  14.  
  15. dGENERATE produces simple, easy to understand algorithms because 
  16. every programmer's needs are different, and there is no single 
  17. algorithm that will work for everyone.  One of dGENERATE's main 
  18. features is that it is written in dBASE III and can be easily 
  19. modified to generate any algorithm you like.
  20.  
  21. Due to the variety of algorithms required for applications 
  22. development, we prefer to maintain a library of routines and 
  23. incorporate the generated code with the appropriate routine for 
  24. each application.
  25.  
  26.  
  27. RIGHTS:
  28.  
  29. You are encouraged to freely distribute copies of dGENERATE to 
  30. anyone you choose, as long as you do not charge for it and the 
  31. original copyright notice and registration information remain 
  32. intact in both the code and documentation.
  33.  
  34. You own the generated code just as if you wrote it yourself; use 
  35. it however you like.  You have the right to use portions of 
  36. dGENERATE's source code, either modified or unmodified, in any 
  37. original application of your own that does not directly compete 
  38. with dGENERATE.  We disclaim all liability and make no guarantee.
  39.  
  40. You are invited to become a registered dGENERATE by sending 
  41. fifteen dollars to us at the above address for which we will send 
  42. you a disk containing the latest version of all the files listed 
  43. below.  Registration also entitles you to full technical support 
  44. by telephone, mail, CompuServe, and the Source.  Only if we have 
  45. you on file can we notify you of updates, bug-fixes, and new 
  46. dBASE-related software.
  47.  
  48.         For UK and Europe registration, our 
  49.         products are supported by:-
  50.         
  51.         P.D. Software Support Ltd.
  52.         The Corner House
  53.         Chelwood Gate
  54.         Sussex RH17 7DD
  55.         Tel 082574 306
  56.  
  57. Registration supports the development and marketing of 
  58. inexpensive software via the "shareware" concept.  Your 
  59. registration makes an important contribution!
  60.  
  61. We feel that dGENERATE belongs to the entire dBASE community, and 
  62. your feedback is highly valued.  If there is anything you think 
  63. should be changed or added to the next version, please write us 
  64. with your comments.  
  65.  
  66. The dGENERATE files are:
  67.  
  68.           Source code: dg_main.prg (7K) and dg_proc.prg (55K)
  69.                          Executes under dBASE III,
  70.                          any version greater than 1.1
  71.       RunTime+ linked: dg.prg (30K)
  72.                          Executes under dBASE III, 
  73.                          any version greater than 1.1 or dBRUN
  74.      Clipper compiled: dg.exe (160K)
  75.                          Executes under MS- or PC-DOS,
  76.                          version 2.0 or higher
  77.                        dg_clip.prg (55K) is the compilable 
  78.                          source code for the Clipper version
  79.              Database: dg.dbf
  80.                          One field 'dg_text', character 254 bytes
  81.         Documentation: dg_doc.txt (20K)
  82.          Announcement: about_us.txt (1K)
  83.  
  84.  
  85. INSTALLATION:
  86.  
  87. "Install" simply means to copy the appropriate files onto your 
  88. working disk.  You only need to install the file or files that 
  89. you will use.  If you want to run source code, install both the 
  90. main and procedure files.  If you want to run the linked file, 
  91. only install dg.prg.  If you do not have a copy of dBASE III 
  92. later than version 1.1, install only dg.exe.  All versions of 
  93. dGENERATE use the dg.dbf system database file.  Once you have 
  94. printed a copy of this documentation file, you do not need it on 
  95. your disk.
  96.  
  97. Hard Disk:
  98.  
  99. This is the easiest way to use dGENERATE.  Set your operating 
  100. system "path" to the directory where dBASE III is installed (see 
  101. your operating system manual).  Now you can call dBASE from 
  102. anywhere.  Once in dBASE III, SET PATH TO the directory where 
  103. dGENERATE is installed.  Now you can use dGENERATE from anywhere 
  104. that you can call dBASE.  The files created by dGENERATE are 
  105. always in the local directory.
  106.  
  107. The editor (word processing software) you specify during <S>etup 
  108. must be accessible from the current directory from which you 
  109. entered dBASE III.  Your editor must be able to find its overlay
  110. files when called from this directory.  If it works from the 
  111. operating system prompt where you enter dBASE, it should work in 
  112. dGENERATE.
  113.  
  114. Floppy Disk:
  115.  
  116. One method is to place a copy of both dGENERATE and your editor 
  117. on a separate disk which is placed in drive B and used as your 
  118. development disk during the application's implementation.
  119.  
  120. The other method is to create a new dBASE III System Disk Two.  
  121. If enough of the optional files are removed from System Disk Two, 
  122. both your editor and dGENERATE can be placed on it in drive A.
  123.  
  124. In either of these floppy schemes, both the DOS file 
  125. "Command.com" and the dBASE III overlay file "Dbase.ovl" must be 
  126. on the disk in drive A.  Your editor's overlay files must be on 
  127. the drive where your editor knows to look for them.
  128.  
  129. If your system has very little memory, you may get an 
  130. "Insufficient Memory" error message from dBASE when it tries to 
  131. RUN your editor.  To correct this, you can add more memory to 
  132. your system or use the compiled version of dGENERATE which 
  133. requires much less memory than the versions that run under dBASE.
  134.  
  135.  
  136. SETUP:
  137.  
  138. There are thirteen sets of parameters that can be changed in the 
  139. setup module by selecting number six <S>etup on the main menu.
  140.  
  141.      1.  Characters that denote SAYs and GETs in a screen-form
  142.                Default: SAY '}', GET '{'
  143.      2.  Character that denotes memory variable in a screen-form
  144.                Default: '~' (the tilde)
  145.      3.  Size of screen-form in rows and columns
  146.                Default: 24 rows, 80 columns
  147.      4.  Relative or literal addressing in @ coordinates
  148.                Default: Literal
  149.      5.  Add the ruler line in screen-form or omit
  150.                Default: Add
  151.      6.  Set delimiters on or off
  152.                Default: Off
  153.      7.  Fill new screen form with blanks or omit
  154.                Default: Omit
  155.      8.  Display help screens or omit
  156.                Default: Display
  157.      9.  File extensions created by dGENERATE
  158.                Default: Screen-form '.dgS' (Screen-form file),
  159.                         generated code '.dgP' (Program file),
  160.                         generated memvars '.dgM' (Memvar file)
  161.     10.  Ruler line characters
  162.                Default: Column zero '0', 
  163.                         every ten columns thereafter '123456789.'
  164.     11.  Delimiter characters
  165.                Default: Left ':', right ':'
  166.     12.  Marquee line character (ASCII value)
  167.                Default: 61      ('=')
  168.     13.  Filename of editor used to draw screen-forms
  169.                Default: none (uses MODIFY COMMAND)
  170.  
  171.           dGENERATE relies on the word processing software you 
  172.           assign for all editing tasks.  If you have assigned an 
  173.           editor in <S>etup, dGENERATE will RUN it for all 
  174.           <E>diting operations.  If not, dGENERATE will call 
  175.           MODIFY COMMAND which will run either the built-in dBASE 
  176.           III word processor or the editor that has been assigned 
  177.           to WP in Config.db.  Because the built-in dBASE III 
  178.           word processor wraps all lines at the 67th column and 
  179.           provides no way to disable this feature, it is most 
  180.           inconvenient for drawing screen-forms.  The use of a 
  181.           more versatile editor is highly recommended.
  182.  
  183.           To use a memory-resident editor such as the one in 
  184.           SideKick, assign "INMEMORY" during <S>etup.  This will 
  185.           prevent the automatic <E>dit after <C>reate.  While at 
  186.           dGENERATE's main menu, call your editor the way you 
  187.           usually do instead of using the <E>dit procedure.  Then 
  188.           save the file, exit the editor, and select <G>enerate 
  189.           to write the code.
  190.  
  191. The "parameters line" is made up of these values and can be saved 
  192. in the system database file.   Part of the parameters line is 
  193. stored in each newly created screen-form file to tell dGENERATE 
  194. what parameters to use in generating code from each screen-form.
  195.  
  196. Change parameters in <S>etup before <C>reating new screen-forms.
  197.  
  198. Change parameters in existing screen-forms by <E>diting the
  199. parameters line in the screen-form itself.
  200.  
  201.  
  202. OPERATION:
  203.  
  204. dGENERATE performs five distinct operations, each of which can be 
  205. called from the main menu.
  206.  
  207.      1.   <C>reate a new screen-form
  208.      2.   <E>dit an existing screen-form
  209.      3.   <G>enerate code from a screen-form
  210.      4.   <D>O (execute) a command file
  211.      5.   Generate <M>emory variable code from a database file
  212.  
  213. Some operations are called automatically from other operations.  
  214. For example, if you create a new screen-form, you are 
  215. automatically placed in it for editing.  Code is automatically 
  216. generated after editing a screen-form, and newly generated 
  217. command files are automatically executed.
  218.  
  219. General:
  220.  
  221. If you are running dGENERATE under regular dBASE III, pressing 
  222. the Escape key will SUSPEND dGENERATE and place you in the 
  223. interactive mode of dBASE III.  Type RESUME to return to 
  224. dGENERATE.  This is useful when you want to create a database 
  225. file or test an expression without exiting and rebooting 
  226. dGENERATE.  If you SUSPEND while in dGENERATE's main menu, you 
  227. must press a key after RESUMing in order to redisplay the menu.
  228.  
  229. dGENERATE uses only one work area, the current one when dGENERATE 
  230. is entered.  However, because the RUN command is used for 
  231. editing, we recommend that you close all open files before 
  232. executing dGENERATE to avoid the possibility of corrupting them.
  233.  
  234. dGENERATE creates temporary files during code generation, but 
  235. erases them when finished or if aborted properly.  These are not 
  236. big, using one 255 byte record for each line in a screen-form, 
  237. but there must be room on the default disk for this file and its 
  238. index file (around 10K).  The first release of dGENERATE does not 
  239. check for adequate diskspace before creating its temporary files.
  240.  
  241. dGENERATE variables all begin with 'dg_' or 'dl_' to avoid 
  242. confusion with other variables on which you might use dGENERATE.  
  243. Avoid naming memvars or fields beginning with 'dg_' or 'dl_' to 
  244. prevent any conflict with dGENERATE.
  245.  
  246. dGENERATE uses the following names for procedures.  An attempt to 
  247. <D>o a command file of the same name will have unpredictable 
  248. results.  Avoid the use of these names for screen-forms: abort, 
  249. alt_file, config, crea_new, doer, editor, file_msg, fileprmt, 
  250. generate, gen_entr, gen_menu, gen_rprt, helper, hlp_crea, 
  251. hlp_doer, hlp_edit, hlp_gene, hlp_mgen, hlp_setu, hlp_togl, 
  252. key_time, line_inc, marquee, mem_gen, pars_lit, pars_var, setup, 
  253. set_if1, set_if2, set_if3, wait_msg, and write.
  254.  
  255. There is a "time-out" feature in dGENERATE.  If you leave 
  256. dGENERATE inactive for three minutes while in the main menu, it 
  257. will clear the screen body and prompt you to press any key to 
  258. re-activate.  If you are in a sub-menu, it will return to the 
  259. main menu.
  260.  
  261. Option 1: <C>reate a new screen-form
  262.  
  263. dGENERATE places several items in a new screen form to set it up 
  264. for your use.  To understand these, we must first define the 
  265. parts of a screen-form.  Every screen-form has three parts, the 
  266. header, the body, and the footer.  The body is where you draw 
  267. your screen or form.  The header contains the ruler line, and the 
  268. footer contains the variable definitions, code generating 
  269. options, and parameters line.
  270.  
  271. If the ruler-line flag is on, dGENERATE places a ruler on the 
  272. first line in the screen-form to assist you in measuring columns 
  273. and placing data.  If the blank-fill flag is on, dGENERATE fills 
  274. the body of the screen-form with blank spaces.  If you reply that 
  275. you want to add memvars from a database file when prompted, 
  276. dGENERATE places the appropriate names in the definition table in 
  277. the footer.
  278.  
  279. Option 2: <E>dit a screen-form (or any text) file
  280.  
  281. If you have specified the form width (columns) in <S>etup, the 
  282. ruler line will be that exact width.  Because it is the first
  283. line in the file, most editors will be positioned to it upon 
  284. entering.  Many editors allow you to set the working margins from
  285. any line on which the cursor appears.  In WordStar, for example, 
  286. you can set your working margins to the proper screen-form width 
  287. by pressing Ctrl-OF (^OF) when the cursor is on the ruler line.
  288.  
  289. You draw your screen-form by writing all literal prompts 
  290. precisely where you want them to appear.  Variables to be 
  291. displayed with either a SAY or a GET are identified by the SAY or 
  292. GET symbol immediately followed by a single character "definition 
  293. symbol" of your choice.  For example:
  294.  
  295.         Name: }a
  296.      Address: {b
  297.         City: {c
  298.  
  299. The GET and SAY symbols '{' and '}' cannot be used for anything 
  300. else.  If you need to use them in the screen-form for something 
  301. else, change the symbols first in <S>etup.  The definition 
  302. symbols 'a', 'b', and 'c' are defined in the definitions table 
  303. below the screen body:
  304.  
  305.      dgDEFINE
  306.      a Name
  307.      b Address
  308.      c City
  309.  
  310. If you want to have a better idea of what your screen or form 
  311. will look like while you are drawing it, you can follow the 
  312. definition symbol with any combination of characters.  All 
  313. characters immediately following a definition symbol are ignored 
  314. until a space is encountered.  For example:
  315.  
  316.         Name: }Full_name_goes_here--------------
  317.      Address: {9300_Wilshire_Boulevard,Suite_470
  318.         City: {*--------------------|  State:}S
  319.  
  320. Memvars may be specified in the definitions table to take the 
  321. place of field names:
  322.  
  323.      dgDEFINE
  324.      F m_name ~ Name
  325.      9 m_address ~ Address
  326.      * m_city ~ City
  327.      S m_state ~ State
  328.  
  329. The definitions table may simply contain expressions instead of 
  330. variables unless a GET is being used on that symbol:
  331.  
  332.      dgDEFINE
  333.      T TIME()
  334.      D DATE()
  335.      & SPACE(20)
  336.  
  337. PICTURE and FUNCTION phrases may be added and there are no 
  338. restrictions about spacing other than beginning with the 
  339. definition symbol in the first column and placing all definitions 
  340. in the "definition table."  The definition table begins with the 
  341. word 'dgDEFINE' on a line in the first column.  The next line is 
  342. an example syntax of a definition.  All definitions are placed 
  343. one per line immediately following the definition table's example 
  344. syntax:
  345.  
  346.      dgDEFINE -- Example syntax follows
  347.      <definition symbol> [<memvar> ~] <expression> [PICTURE <phrase>]
  348.      1 "All definitions go here"
  349.      2 m_var ~ "and here" PICTURE "AAAXAAAA"
  350.      3 "and so on..." FUNCTION "!"
  351.      a "Note that lowercase and"
  352.      A "uppercase are different symbols."
  353.  
  354. If you answered that you want memvars added from a database file 
  355. during the <C>reate a screen-form process, the definition table 
  356. will look like this:
  357.  
  358.      dgDEFINE
  359.        m_name ~ Name
  360.        m_address ~ Address
  361.        m_city ~ City
  362.  
  363. You simply add the definition symbol that you use in the screen 
  364. body to the first column of each definition.  You can also add 
  365. PICTURE or FUNCTION clauses and && comments if desired:
  366.  
  367.      dgDEFINE
  368.      1 m_name ~ Name  FUNCTION "!"  && uppercase key expression
  369.      2 m_address ~ Address
  370.      3 m_city ~ City
  371.  
  372. All definitions must fit on one line, and cannot be continued 
  373. with a semicolon.  Leave a blank line after your definitions are 
  374. completed.
  375.  
  376. dGENERATE options are dgFILE, dgENTRY, dgMENU, and dgREPORT.  
  377. Options can be declared anywhere in a screen-form as long as they 
  378. begin a line in the first column.  Only one dgFILE may be 
  379. declared in each screen-form.  If more than one is declared, only 
  380. the first will be used.  Only one of the dgENTRY, dgMENU, or 
  381. dgREPORT options may be declared.  If more are declared, only the 
  382. first in this order of precedence will be used: dgENTRY, dgMENU, 
  383. dgREPORT.
  384.  
  385.      dgFILE <database filename> 
  386.           Writes the code for opening and closing a database file.
  387.      dgENTRY
  388.           Writes the algorithm for data entry or edit.
  389.      dgMENU
  390.           Writes the algorithm for menu driven user selections.
  391.           Uses INKEY() algorithm, and you specify the characters 
  392.           for each CASE statement on a separate line below the 
  393.           dgMENU declaration.
  394.      dgREPORT
  395.           Writes the algorithm for printed reports.
  396.           Requires use of a database file (can use dgFILE).
  397.  
  398. dgFILE takes only the filename, not the DBF extension:
  399.      dgFILE Names
  400.  
  401. dgMENU requires allowable characters for each CASE be listed 
  402. without delimiters on a new line directly below the dgMENU 
  403. declaration.  Each line represents the keys that may be pressed 
  404. to select one option from the menu:
  405.      dgMENU
  406.      Aa1
  407.      Bb2
  408.      Cc3
  409.      Qq
  410.  
  411. dgREPORT writes code that uses the printer.  Be sure your printer 
  412. is on line when using this option or executing the generated 
  413. code.  Maximum form size is 254 columns by 999 rows.  GETs are 
  414. automatically converted to SAYs so that you can re-use screen-
  415. forms originally drawn for data entry.
  416.  
  417. Option 3: <G>enerate code from screen-form
  418.  
  419. Sit back and relax while dGENERATE does the work.  Part of the 
  420. code written is to initialize a variable called 'undefined' with 
  421. three asterisks.  This prevents a generated program from crashing 
  422. when a memvar initialization is overlooked.
  423.  
  424. If the relative addressing flag is on, dGENERATE will write the 
  425. @ coordinates using the ROW() function.  PROW() is used if it is 
  426. declared as a report with dgREPORT.  Only ROW() and PROW() are 
  427. generated as functions, and literal addresses are used in place 
  428. of COL() and PCOL() regardless of the flag status.
  429.  
  430. Option 4: <D>o a command file
  431.  
  432. "***" appearing in your screen or form means that a variable has 
  433. not been properly defined or initialized.
  434.  
  435. When DOing a newly generated command file, dGENERATE displays the
  436. screen and then does an invisible WAIT before returning to the 
  437. Main Menu.  This is necessary in order to see the results of your 
  438. screen-form, but provides no prompt to press a key unless you 
  439. have included one in your screen.  Remember to press a key to 
  440. return to the menu after you have seen your generated screen 
  441. displayed.
  442.  
  443. If a DO file crashes, select SUSPEND, then type RETURN and 
  444. RESUME.  This will place you back in dGENERATE's Main Menu.
  445.  
  446. This option is not available in the compiled version of dGENERATE 
  447. because the generated dBASE code needs a dBASE interpreter to 
  448. run, or it must be compiled first.  The compiled dGENERATE offers 
  449. access to DOS in this place where the generated code can be 
  450. compiled or the dBASE interpreter can be called.  None of this is 
  451. automated because the code is likely to be incorporated with 
  452. other code before compiling is desirable.
  453.  
  454. Option 5: <M>ake memvars from fields
  455.  
  456. Just give dGENERATE the name of a database file, and it will
  457. create memvar names from the field names and write initialization
  458. and REPLACE commands.
  459.  
  460. Two kinds of initialization statements are generated.  One from 
  461. the field names:
  462.  
  463.      m_name     = Name
  464.      m_start_da = Start_date
  465.      m_amount   = Amount
  466.  
  467. The other from expressions:
  468.  
  469.      m_name     = SPACE( 35)
  470.      m_start_da = CTOD("  /  /  ")
  471.      m_amount   = 0000.00
  472.  
  473. The REPLACE statements:
  474.  
  475.      REPLACE Name       WITH m_name 
  476.      REPLACE Start_date WITH m_start_da
  477.      REPLACE Amount     WITH m_amount
  478.  
  479. This code is not intended to run as it stands.  It is meant to be
  480. incorporated into the code that you write for each application.
  481.  
  482. Note that the memory variable names only use the first eight
  483. characters of the field names.  When CREATing your database 
  484. files, keep significant letters within the first eight letters:
  485.  
  486.      'Fieldname1' and 'Fieldname2' both generate 'm_fieldnam'
  487.      'Field_1' and 'Field_2' generate 'm_field_1' and 'm_field_2'
  488.  
  489.  
  490. TECHNICAL SUPPORT:
  491.  
  492. Electronic mail on CompuServe or the Source is the best way.  
  493. Regular postal mail is good if your needs are not immediate.  We 
  494. also offer support by telephone, but cannot guarantee that a 
  495. technical person will be available when you call.  However, a 
  496. programmer will return your call the same or following working 
  497. day.  All long distance support calls are returned COLLECT in 
  498. order to keep the price of dGENERATE as low as possible.  
  499. Remember, we only charge fifteen dollars.
  500.  
  501. Please do NOT call Ashton-Tate or Nantucket for dGENERATE 
  502. support.  They are very busy supporting their own products.
  503.  
  504.  
  505. TRADEMARKS:
  506.  
  507.           Ashton-Tate:  dBASE, dBASE III, RunTime+
  508.               Borland:  SideKick
  509.                   IBM:  PC-DOS
  510.              MicroPro:  WordStar
  511.             Microsoft:  MS-DOS
  512.             Nantucket:  Clipper
  513. Tom Rettig Associates:  dGENERATE
  514.  
  515.  
  516.               *** EOF: dGENERATE Documentation ***
  517.